HTTP-API (API-Tokens)

Admin Power Pack stellt die Wartungsbefehle und Systemaktionen des Tabs zusätzlich über eine REST-artige HTTP-Schnittstelle bereit. Sie authentifiziert über statische API-Tokens (Authorization: Bearer), die im Modul erzeugt und widerrufen werden — ohne STARFACE-Benutzerkonto und ohne die kurzlebigen OAuth2-Access-Tokens der Anlage. Gedacht für dauerhaft angebundene Drittsysteme wie ERP/Warenwirtschaft, RMM- und Deployment-Werkzeuge, für die die Anmeldung der XML-RPC-Schnittstelle unpraktisch ist.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Verfügbar ab der nächsten Modulversion

Die HTTP-API und die API-Token-Verwaltung sind in den Modulversionen bis einschließlich 26.7.28 noch nicht enthalten und erscheinen mit der nächsten Modulversion.

Grundlagen

Typ: HTTP(S)-Endpunkt mit JSON-Antworten (application/json)
Basis-URL: https://<starface-host>/fp/7ce0d8df/api/v1 — 7ce0d8df ist die feste Modulkennung von Admin Power Pack (die ersten acht Zeichen der Modul-ID 7ce0d8df-e9c8-42f6-a021-7a6e0bb44b88), auf jeder Anlage identisch. Erreichbarkeit wie die Weboberfläche (STARFACE-Webserver, 443/TCP).
Authentifizierung: statischer API-Token im Header Authorization: Bearer <Token> (siehe API-Tokens verwalten). Der Pfad /fp/…/api/… liegt außerhalb der STARFACE-Anmeldung — die Token-Prüfung des Moduls ist die einzige Zugangskontrolle.
Nutzlast: JSON im Request-Body (nur bei POST), maximal 1 MiB je Anfrage
Antwortverhalten: Ein angenommener Befehl antwortet sofort; die Ausführung läuft asynchron im Hintergrund — identisch zur XML-RPC-Schnittstelle. Das Feld trigger setzt das Modul serverseitig immer auf API.
Lizenz: Die Annahme des Aufrufs erfolgt unabhängig von der Lizenz, die Ausführung ist lizenzgebunden — ohne gültige Modullizenz wird der angenommene Befehl verworfen (Eintrag im Modul-Log, kein Abschlussereignis).
Verfügbar ab: der nächsten Modulversion nach 26.7.28

API-Tokens verwalten

API-Tokens werden in der Moduloberfläche verwaltet: Tab , Karte Sicherheit, Schaltfläche API-Tokens. Die Verwaltung erfordert das Administrationsrecht.

Erzeugen: Vergeben Sie eine Bezeichnung (z. B. „ERP-Anbindung") und optional ein Ablaufdatum. Der Token ist ein kryptografisch zufälliges Geheimnis (32 Byte, Base64url) und wird genau einmal im Klartext angezeigt — kopieren Sie ihn sofort. Die Anlage speichert danach ausschließlich einen SHA-256-Hash; der Klartext ist nicht wiederherstellbar.
Gültigkeit: Tokens ohne Ablaufdatum gelten unbegrenzt; abgelaufene Tokens werden mit 401 abgelehnt. Die Liste zeigt je Token Erstellungszeitpunkt, Ablauf und letzte Nutzung.
Widerrufen: Das Löschen eines Tokens macht ihn sofort ungültig.
Berechtigung: Ein gültiger Token berechtigt zum Aufruf aller Endpunkte dieser HTTP-API. Eine Einschränkung einzelner Tokens auf bestimmte Befehle gibt es nicht.

Token wie ein Passwort behandeln

Wer den Token kennt, kann sämtliche Wartungsbefehle und Systemaktionen der Anlage auslösen — einschließlich Neustart, Update und unwiderruflicher Löschaktionen. Die HTTP-API besitzt kein eigenes Ratenlimit und keine IP-Beschränkung. Übertragen Sie Tokens nur über sichere Kanäle, hinterlegen Sie je System einen eigenen Token und widerrufen Sie ihn bei Verdacht auf Weitergabe.

Endpunkte

`GET /v1/system-functions`

Listet die Namen der verfügbaren Befehle auf.

curl
Python

curl -s -H "Authorization: Bearer $API_TOKEN" \
  "https://pbx.example.de/fp/7ce0d8df/api/v1/system-functions"

import requests

BASE = "https://pbx.example.de/fp/7ce0d8df/api/v1"
TOKEN = "…"   # einmalig angezeigter API-Token

r = requests.get(f"{BASE}/system-functions",
                 headers={"Authorization": f"Bearer {TOKEN}"})
print(r.json()["commands"])

Antwort 200 OK:

{
  "commands": [
    "RunAutoCleanup", "DeleteSystemMessages", "DeleteLogs", "DeleteTemporaryFiles",
    "DeleteRecordings", "DeleteFaxes", "DeleteCallData", "DeleteFirmware",
    "DeleteBackups", "ReRegisterTrunks", "HangupAllCalls", "ProvisionDevices",
    "RestartStarface", "UpdateStarface"
  ]
}

`POST /v1/system-functions/<Befehl>`

Löst den Befehl aus. <Befehl> ist einer der Namen aus GET /v1/system-functions; Wirkung und Parameter je Befehl sind identisch mit der XML-RPC-Referenz und werden dort dokumentiert. Die Parameter werden als JSON-Objekt im Request-Body übergeben; ohne Parameter darf der Body leer bleiben.

Gegenüber XML-RPC gelten die nativen JSON-Datentypen: Boolesche Parameter als true/false, Millisekunden-Zeitstempel (startTime, endTime) als JSON-Zahl — die Zeichenketten-Behelfslösung der XML-RPC-Schnittstelle ist hier nicht nötig. Unbekannte Felder werden ignoriert; trigger setzt das Modul serverseitig auf API. Ein syntaktisch ungültiger JSON-Body wird verworfen und der Befehl ohne Parameter ausgeführt — bei Befehlen mit Pflichtparametern (DeleteCallData, ProvisionDevices) wird die Ausführung dann still verworfen.

curl
Python

curl -s -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scope": "old"}' \
  "https://pbx.example.de/fp/7ce0d8df/api/v1/system-functions/DeleteLogs"

r = requests.post(f"{BASE}/system-functions/DeleteLogs",
                  headers={"Authorization": f"Bearer {TOKEN}"},
                  json={"scope": "old"})
print(r.json()["status"])   # "ok"

Antwort 200 OK — bestätigt die Annahme, nicht das Ergebnis:

{"status": "ok"}

Den Abschluss meldet je Wartungsaktion ein Ereignis; die Systemaktionen RestartStarface und UpdateStarface senden keines.

Anwendungsbeispiel

Rollout über viele Anlagen: Ihr Deployment-Skript hinterlegt je Anlage einen API-Token und plant nachts ein Update — ohne STARFACE-Benutzerkonto und ohne ablaufende Zugangsdaten:

r = requests.post(f"{BASE}/system-functions/UpdateStarface",
                  headers={"Authorization": f"Bearer {TOKEN}"},
                  json={"version": "latest", "executeAt": "2026-08-12T22:00"})

Planungsverhalten (executeAt, Ersetzen, Abbrechen, Nachholen verpasster Zeitpunkte) wie beim XML-RPC-Befehl UpdateStarface beschrieben.

Fehlerbehandlung

Transportfehler beantwortet die Schnittstelle mit HTTP-Statuscodes und einem JSON-Objekt (status = "error", message mit der Ursache); fachliche Sonderfälle verwirft das Modul bewusst still mit 200 — dieselben Fälle wie bei der XML-RPC-Schnittstelle:

Status	Situation	Antwort-`message`
`401`	Token fehlt, ist ungültig, widerrufen oder abgelaufen	`invalid or missing API token`
`404`	Unbekannter Pfad oder falsche HTTP-Methode	`unknown endpoint`
`404`	Unbekannter Befehlsname	`unknown command`
`413`	Request-Body größer als 1 MiB	abweichendes Format: `{"ok": false, "error": "body-too-large"}`
`500`	Befehl konnte intern nicht weitergereicht werden	`command failed`
`200`	Fachlicher Sonderfall (fehlende Lizenz, `DeleteCallData` ohne `confirmed`, `ProvisionDevices` ohne `type`, ungültiger `mode`, nicht verfügbare Zielversion)	`status` = `"ok"`, Ausführung wird still verworfen — Details im Modul-Log

Anders als bei der XML-RPC-Schnittstelle werden fehlgeschlagene Token-Prüfungen nicht an die STARFACE-Sicherheitsüberwachung gemeldet; es erfolgt keine automatische IP-Sperre.

Versionierung & Kompatibilität

Die API ist über den Pfadbestandteil v1 versioniert. Abwärtskompatible Erweiterungen — neue Befehle in der Liste, neue optionale Parameter — erfolgen ohne Versionswechsel; Breaking Changes führen zu v2 und werden in den Release Notes angekündigt. Der Befehlsumfang ist kuratiert und entspricht den Funktionen, deren Popover im Tab STARFACE Verwaltung einen API-Aufruf anbietet; der dortige Dialog zeigt derzeit die XML-RPC-Variante.

Grundlagen​

API-Tokens verwalten​

Endpunkte​

GET /v1/system-functions​

POST /v1/system-functions/<Befehl>​

Fehlerbehandlung​

Versionierung & Kompatibilität​